docs/config.json-181-183 (1)

181-183: ⚠️ Potential issue | 🟡 Minor

Fix broken docs path for Solid plugin example.

Line 182 uses framework/solif/..., which looks like a typo and will produce a broken link.

Fix

-              "to": "framework/solif/examples/a11y-devtools"
+              "to": "framework/solid/examples/a11y-devtools"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/config.json` around lines 181 - 183, The "to" path for the A11y example
is misspelled as "framework/solif/examples/a11y-devtools" causing a broken docs
link; update the "to" value (the JSON entry paired with "label": "A11y") to the
correct path "framework/solid/examples/a11y-devtools" so the link resolves to
the Solid plugin example.

docs/plugins/a11y.md-10-10 (1)

10-10: ⚠️ Potential issue | 🟡 Minor

Use “Full-Page Scanning” for compound adjective consistency.
Small docs polish: hyphenate “Full Page” when used adjectivally.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/plugins/a11y.md` at line 10, Replace the adjectival phrase "Full Page
Scanning" with the hyphenated "Full-Page Scanning" in the docs text (the
occurrence in docs/plugins/a11y.md), ensuring the compound adjective is
consistently hyphenated wherever the phrase is used as a descriptor.

packages/devtools-a11y/tests/config.test.ts-27-34 (1)

27-34: ⚠️ Potential issue | 🟡 Minor

Add vi.unstubAllGlobals() in the afterEach hook to properly clean up global stubs.

The config does not enable unstubGlobals: true, so vi.restoreAllMocks() alone will not undo the vi.stubGlobal('localStorage') call. Without cleanup, the mocked localStorage will leak into later test suites. Either add vi.unstubAllGlobals() here or enable unstubGlobals: true in the Vitest config.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/tests/config.test.ts` around lines 27 - 34, The
afterEach cleanup currently calls vi.restoreAllMocks() but does not undo globals
stubbed by vi.stubGlobal('localStorage') in beforeEach; update the afterEach
hook to also call vi.unstubAllGlobals() (in addition to vi.restoreAllMocks()) to
ensure the stubbed global localStorage from localStorageMock is removed between
tests, referencing the existing beforeEach/afterEach and the
vi.stubGlobal('localStorage') usage so the global cleanup is applied correctly.

examples/solid/a11y-devtools/.eslintrc.cjs-4-9 (1)

4-9: ⚠️ Potential issue | 🟡 Minor

Move extends and rules to the ESLint config top level.

In legacy .eslintrc.* format, extends and rules are top-level config properties. The settings key is reserved for shared plugin data only. Lines 6–7 place them incorrectly under settings, where ESLint does not read them.

Proposed fix

 const config = {
-  settings: {
-    extends: [],
-    rules: {},
-  },
+  extends: [],
+  rules: {},
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/solid/a11y-devtools/.eslintrc.cjs` around lines 4 - 9, The ESLint
config puts extends and rules under the reserved settings key so ESLint ignores
them; update the exported config object named config by moving extends and rules
out of config.settings into the top-level config (keep config.settings only for
plugin shared data or remove it if unused), e.g., ensure config.extends = [...]
and config.rules = {...} and delete these keys from config.settings so ESLint
reads them correctly.

examples/react/a11y-devtools/src/App.tsx-66-68 (1)

66-68: ⚠️ Potential issue | 🟡 Minor

Mismatched comment and heading.

The JSX comment on line 66 says "Missing main landmark" but the corresponding heading says "Click handler on non-interactive element". Update the comment to match the demonstrated issue.

✏️ Proposed fix

-        {/* Issue: Missing main landmark */}
+        {/* Issue: Click handler on non-interactive element */}
         <div style={{ marginBottom: '16px' }}>
           <h3>6. Click handler on non-interactive element</h3>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/react/a11y-devtools/src/App.tsx` around lines 66 - 68, Update the
JSX comment above the example to match the displayed issue: change the comment
text in the div block that contains the h3 ("6. Click handler on non-interactive
element") so the comment reads "Click handler on non-interactive element"
instead of "Missing main landmark"; locate the comment in the same JSX fragment
containing the div and h3 in App (App.tsx) and replace the mismatched comment
text accordingly.

examples/solid/a11y-devtools/src/app.tsx-63-65 (1)

63-65: ⚠️ Potential issue | 🟡 Minor

Mismatched comment and heading.

Same issue as in the React example: the JSX comment says "Missing main landmark" but the heading says "Click handler on non-interactive element".

✏️ Proposed fix

-        {/* Issue: Missing main landmark */}
+        {/* Issue: Click handler on non-interactive element */}
         <div style="margin-bottom: 16px;">
           <h3>6. Click handler on non-interactive element</h3>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/solid/a11y-devtools/src/app.tsx` around lines 63 - 65, The inline
JSX comment above the example div is inconsistent with its heading: update
either the JSX comment or the <h3> text so they match; locate the div with
style="margin-bottom: 16px" that contains the <h3> and change the comment to
"Click handler on non-interactive element" to match the heading (or
alternatively change the <h3> to "Missing main landmark" if that was intended).

packages/devtools-a11y/src/core/utils/ally-audit.utils.ts-110-123 (1)

110-123: ⚠️ Potential issue | 🟡 Minor

Potential ID collision in rapid iteration.

Using Date.now() for ID generation within a synchronous loop can produce duplicate IDs when multiple nodes are processed within the same millisecond. Additionally, Date.now() is called twice per issue (once for id, once for timestamp).

🔧 Suggested fix

+let issueCounter = 0
+
 function convertToIssues(
   results: AxeResults,
   threshold: SeverityThreshold,
 ): Array<A11yIssue> {
   const issues: Array<A11yIssue> = []
+  const batchTimestamp = Date.now()

   for (const violation of results.violations) {
     const impact = violation.impact as SeverityThreshold | undefined

     for (let i = 0; i < violation.nodes.length; i++) {
       const node = violation.nodes[i]!
       const selector = node.target.join(', ')

       const a11yNode: A11yNode = {
         selector,
         html: node.html,
         xpath: node.xpath?.join(' > '),
         failureSummary: node.failureSummary,
       }

       issues.push({
-        id: `${violation.id}-${i}-${Date.now()}`,
+        id: `${violation.id}-${i}-${batchTimestamp}-${issueCounter++}`,
         ruleId: violation.id,
         impact: impact || 'minor',
         message: node.failureSummary || violation.description,
         help: violation.help,
         helpUrl: violation.helpUrl,
         wcagTags: violation.tags.filter(
           (tag) => tag.startsWith('wcag') || tag.startsWith('section508'),
         ),
         nodes: [a11yNode],
         meetsThreshold: meetsThreshold(impact, threshold),
-        timestamp: Date.now(),
+        timestamp: batchTimestamp,
       })
     }
   }

   return issues
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ally-audit.utils.ts` around lines 110 -
123, The issue: IDs use Date.now() inside the synchronous loop (and called
twice) which can collide; fix by generating a stable timestamp and a truly
unique id per issue. Before pushing, compute a single timestamp variable (e.g.,
const timestamp = Date.now()) and reuse it for the timestamp field, and replace
the id generation with a collision-resistant value (e.g., use
crypto.randomUUID() or append a short random/nonce to
`${violation.id}-${i}-${timestamp}`) so each issue created in the same
millisecond is unique; keep other fields (ruleId, message, help, wcagTags,
nodes, meetsThreshold) unchanged.

packages/devtools-a11y/src/core/utils/ally-audit.utils.ts-240-245 (1)

240-245: ⚠️ Potential issue | 🟡 Minor

Incorrect type assertion on include array element.

When context is a Document, casting it as Element at line 242 violates type safety. The include array should accept Node (which covers both Document and Element), not just Element. Change the cast to as Node or use as any if Node is not available, since axe-core's ElementContext accepts Node rather than the narrower Element type.

    if (allExclusions.length > 0) {
      auditContext = {
        include: [auditContext as Node],
        exclude: allExclusions.map((sel) => [sel]),
      } as axe.ElementContext
    }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ally-audit.utils.ts` around lines 240 -
245, The current code casts auditContext to Element when building the
axe.ElementContext (in the if block checking allExclusions.length) which is
unsafe if auditContext can be a Document; change the include array element cast
from Element to Node (e.g., use auditContext as Node) so the type matches
axe-core's ElementContext, and keep the exclude mapping as-is
(allExclusions.map((sel) => [sel])) while preserving the final as
axe.ElementContext assertion.

examples/react/start/src/routes/__root.tsx (2)

1-1: Use a type-only import for ReactNode on Line 1.

Since React is only used for the React.ReactNode type annotation and the project uses the modern jsx: "react-jsx" transform, import ReactNode as a type-only import.

♻️ Proposed fix

-import * as React from 'react'
+import type { ReactNode } from 'react'
@@
-function RootDocument({ children }: { children: React.ReactNode }) {
+function RootDocument({ children }: { children: ReactNode }) {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/react/start/src/routes/__root.tsx` at line 1, Replace the namespace
import "import * as React from 'react'" with a type-only import and update
usages: change to "import type { ReactNode } from 'react'" and replace any
"React.ReactNode" annotations with "ReactNode" (e.g., in the return/props types
or component signatures); this keeps the runtime bundle free of an unused React
import while preserving the type annotation.

---

39-50: Hoist the plugins array to module scope to avoid unnecessary recalculations.

The plugins array is recreated on every RootDocument render. Since TanStackDevtools includes this in a useMemo dependency array (packages/react-devtools/src/devtools.tsx:172), each new reference triggers recalculation and a subsequent useEffect that calls devtools.setConfig(). Moving plugins to module scope stabilizes the reference and eliminates this overhead.

♻️ Proposed fix

+const DEVTOOLS_PLUGINS = [
+  {
+    name: 'Tanstack Router',
+    render: <TanStackRouterDevtoolsPanel />,
+  },
+  {
+    id: 'route-navigation',
+    name: 'Route Navigation',
+    render: <RouteNavigationPanel />,
+  },
+]
+
 function RootDocument({ children }: { children: ReactNode }) {
   console.log('Rendering Root Document')
-  const plugins = [
-    {
-      name: 'Tanstack Router',
-      render: <TanStackRouterDevtoolsPanel />,
-    },
-    {
-      id: 'route-navigation',
-      name: 'Route Navigation',
-      render: <RouteNavigationPanel />,
-    },
-  ]
@@
-          plugins={plugins}
+          plugins={DEVTOOLS_PLUGINS}
         />

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/react/start/src/routes/__root.tsx` around lines 39 - 50, The plugins
array is being recreated on every RootDocument render causing unstable
references for TanStackDevtools (which uses it in a useMemo dependency) and
triggering unnecessary devtools.setConfig() calls; fix this by hoisting the
plugins declaration to module scope (move the const plugins = [...] out of the
RootDocument component) so the same array reference is reused, and keep the
existing items (TanStackRouterDevtoolsPanel, RouteNavigationPanel) intact when
referenced by TanStackDevtools/Devtools.

packages/devtools/src/devtools.tsx (1)

194-200: Consider restoring previous root dataset value on cleanup.

This currently leaves a global data-tanstack-devtools-theme side effect after unmount. Cleanup would make it safer for embed/test scenarios.

Possible refactor

   createEffect(() => {
     if (typeof document === 'undefined') {
       return
     }
-
-    document.documentElement.dataset.tanstackDevtoolsTheme = theme()
+    const root = document.documentElement
+    const prev = root.dataset.tanstackDevtoolsTheme
+    root.dataset.tanstackDevtoolsTheme = theme()
+    onCleanup(() => {
+      if (prev === undefined) {
+        delete root.dataset.tanstackDevtoolsTheme
+      } else {
+        root.dataset.tanstackDevtoolsTheme = prev
+      }
+    })
   })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools/src/devtools.tsx` around lines 194 - 200, The effect
currently sets document.documentElement.dataset.tanstackDevtoolsTheme but never
restores it on unmount; capture the previous value (e.g. const prev =
document.documentElement.dataset.tanstackDevtoolsTheme) before assigning
theme(), then register a cleanup to restore it (if prev is undefined delete the
dataset key, otherwise set it back) using Solid's onCleanup inside the
createEffect; update the createEffect block that uses theme() and
document.documentElement.dataset.tanstackDevtoolsTheme to perform this
save-assign-restore sequence.

packages/devtools-a11y/tests/index.test.ts (1)

3-6: Replace tautological test with a real smoke assertion.

Line 5 always passes and won’t catch regressions. Please assert an actual export/runtime behavior for the package entrypoint.

Suggested direction

 describe('devtools', () => {
-  it('should pass', () => {
-    expect(true).toBe(true)
+  it('exports the public entrypoint', async () => {
+    const mod = await import('../src/index')
+    expect(mod).toBeTruthy()
   })
 })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/tests/index.test.ts` around lines 3 - 6, Replace the
tautological assertion in the test (the it block under describe('devtools'))
with a real smoke assertion that exercises the package entrypoint: import or
require the package's entrypoint (the module exported by the package under test)
and assert the export exists and has the expected shape (e.g.,
expect(entrypoint).toBeDefined() and if it should be a function assert typeof
entrypoint === 'function' or call it and assert a basic return/behavior). Update
the test body to import the module, check the exported symbol(s) (default export
or named exports) and perform one simple runtime assertion rather than
expect(true).toBe(true).

packages/devtools-a11y/eslint.config.js (1)

7-9: Drop the empty package-level rules block unless overrides are planned.
It currently has no effect and can be removed for clarity.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/eslint.config.js` around lines 7 - 9, Remove the empty
top-level "rules" property from the exported config object in eslint.config.js
since it has no effect; locate the object literal that contains rules: {} and
delete that key (or replace it with a clear comment if you intend to add
overrides later) so the package-level config is cleaner and only contains
meaningful settings.

packages/devtools/src/tabs/plugin-registry.ts (1)

224-224: Framework metadata on Line 224 is too narrow for this package.

This entry marks the plugin as react, but this PR adds Solid support too. Consider setting framework to other (or extending metadata model) so marketplace filtering doesn’t hide it from non-React users.

Suggested metadata adjustment

-    framework: 'react',
+    framework: 'other',
-    tags: ['TanStack', 'a11y'],
+    tags: ['TanStack', 'a11y', 'react', 'solid'],

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools/src/tabs/plugin-registry.ts` at line 224, The plugin
metadata sets framework: 'react' in the registry entry (the object literal that
includes the framework property), which is too narrow now that Solid support is
added; update that metadata by changing framework to a more generic value such
as 'other' (or add a neutral value like 'multiple' or expand the metadata model
to accept an array like frameworks: ['react','solid']) so marketplace filtering
won't exclude non-React users; locate the object containing framework: 'react'
in plugin-registry.ts (the registry entry for this plugin) and replace the
single-framework value with a generic or multi-framework representation and
update any consuming code that expects a string if necessary.

examples/react/a11y-devtools/src/App.tsx (1)

144-164: Modal accessibility implementation could be enhanced.

While this is a demo app, the modal in the "Accessible Content" comparison section could demonstrate additional best practices:

• Add aria-modal="true" to indicate it's a modal dialog
• Consider demonstrating focus management (focus trap, return focus on close)

Since this is an example app showcasing accessibility, demonstrating a fully accessible modal would provide a better reference for users.

♿ Suggested enhancement

       {showModal && (
         <div
           role="dialog"
+          aria-modal="true"
           aria-labelledby="modal-title"
           style={{

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/react/a11y-devtools/src/App.tsx` around lines 144 - 164, Update the
modal implemented where showModal is used (the div with role="dialog" and id
"modal-title") to include aria-modal="true" and implement simple focus
management: when opening (showModal becomes true) save the element that
triggered the modal, move focus to the dialog or its first focusable child, trap
Tab/Shift+Tab inside the dialog, handle Escape to call setShowModal(false), and
on close restore focus to the saved trigger; ensure the existing Close button
still calls setShowModal(false) and that focus restoration happens after
closing.

packages/devtools-a11y/src/react/A11yDevtools.ts (1)

7-7: Consider adding JSDoc for the exported interface.

A11yDevtoolsReactInit is a public API type. Adding documentation would help users understand its purpose and how to extend it. As per coding guidelines, JSDoc should read like documentation as it gets converted to markdown docs for the website.

📝 Suggested documentation

-export interface A11yDevtoolsReactInit extends DevtoolsPanelProps {}
+/**
+ * Initialization options for the A11y DevTools React panel.
+ * Extends the base DevTools panel properties.
+ */
+export interface A11yDevtoolsReactInit extends DevtoolsPanelProps {}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/react/A11yDevtools.ts` at line 7, Add a JSDoc
comment above the exported interface A11yDevtoolsReactInit (which extends
DevtoolsPanelProps) describing its purpose as the React initialization props for
the A11y Devtools panel, what properties consumers can expect/extend, and any
usage notes or examples; keep the comment concise and formatted for doc
generation (summary sentence, longer description, and any `@remarks` or `@example`
if relevant) so the public API is documented for the website.

examples/solid/a11y-devtools/src/app.tsx (1)

124-134: Modal accessibility could be enhanced.

Same as the React example, consider adding aria-modal="true" for a more complete accessible modal demonstration.

♿ Suggested enhancement

       {showModal() && (
         <div
           role="dialog"
+          aria-modal="true"
           aria-labelledby="modal-title"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/solid/a11y-devtools/src/app.tsx` around lines 124 - 134, The modal
div rendered when showModal() is true currently has role="dialog" and
aria-labelledby="modal-title" but lacks aria-modal; update the dialog element
(the div controlled by showModal() / closed via setShowModal(false)) to include
aria-modal="true" (keeping role="dialog" and aria-labelledby="modal-title") so
screen readers treat it as a modal.

examples/solid/a11y-devtools/tsconfig.json (1)

1-24: Consider adding path alias for consistency with the React example (optional).

The React example's tsconfig.json includes a paths configuration for @tanstack/devtools-a11y/* for explicit source mapping during development, while this Solid example relies on pnpm workspace resolution. Both approaches work correctly with workspace:* dependencies and the current configuration, but adding the path alias would improve consistency across examples and provide better IDE support.

Path alias configuration (optional improvement)

{
  "compilerOptions": {
    ...
    "paths": {
      "@tanstack/devtools-a11y/*": ["../../../packages/devtools-a11y/src/*"]
    }
  }
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/solid/a11y-devtools/tsconfig.json` around lines 1 - 24, Add an
optional TypeScript path alias under compilerOptions to match the React example
and improve IDE source mapping: add a "paths" entry mapping
"@tanstack/devtools-a11y/*" to the local source (e.g.
"../../../packages/devtools-a11y/src/*") alongside existing compilerOptions keys
so editors resolve imports consistently with the workspace dependency; update
the tsconfig.json's compilerOptions to include "paths" with that alias.

packages/devtools-a11y/src/core/components/IssueList.tsx (1)

83-85: Minor: Redundant fallback value.

The || 0 fallback is unnecessary since Array.length always returns a non-negative number.

Suggested fix

             const issuesForImpact = () =>
               ally.filteredIssues().filter((issue) => issue.impact === impact)
-            const count = () => issuesForImpact().length || 0
+            const count = () => issuesForImpact().length

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/components/IssueList.tsx` around lines 83 -
85, The count function currently returns issuesForImpact().length || 0 which is
redundant because Array.length is always a non-negative number; update the count
function to return issuesForImpact().length (remove the "|| 0" fallback) —
locate the definitions of issuesForImpact and count in IssueList.tsx and
simplify count to directly return the length.

packages/devtools-a11y/src/core/components/Settings.tsx (1)

24-25: Consider whether availableRules needs to be a memo.

Since getAvailableRules() has no reactive dependencies, wrapping it in createMemo provides no reactivity benefits. A simple variable assignment would suffice unless you anticipate adding reactive dependencies later.

Alternative (if no future reactive dependencies expected)

   const disabledRulesSet = createMemo(() => new Set(config.disabledRules))
-  const availableRules = createMemo(() => getAvailableRules())
+  const availableRules = () => getAvailableRules()

Note: Keep as createMemo if getAvailableRules() is expensive and you want to cache the result.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/components/Settings.tsx` around lines 24 -
25, availableRules is wrapped in createMemo but getAvailableRules() has no
reactive inputs, so remove the unnecessary memoization: replace the createMemo
call for availableRules with a plain assignment (const availableRules =
getAvailableRules()) unless you intentionally want to cache an expensive result;
update the symbol availableRules and the call site that references it if needed,
keeping createMemo only for disabledRulesSet which depends on config.

packages/devtools-a11y/src/core/utils/custom-audit.utils.ts (2)

436-440: Stale comment can be removed.

The comment on lines 438-439 about "adding a parameter in the function signature" for threshold is outdated—the threshold parameter already exists in the function signature (line 434).

Proposed fix

 function checkMouseOnlyEvents(
   context: Document | Element = document,
   threshold: SeverityThreshold = 'serious',
 ): Array<A11yIssue> {
   const issues: Array<A11yIssue> = []
   const timestamp = Date.now()
-  // default threshold will be provided by runCustomRules
-  // We'll accept threshold by adding a parameter in the function signature

   // Build selector for elements with mouse events

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/custom-audit.utils.ts` around lines 436
- 440, Remove the stale comment lines that say "// default threshold will be
provided by runCustomRules" and "// We'll accept threshold by adding a parameter
in the function signature" because the threshold parameter already exists;
locate the block where const issues: Array<A11yIssue> and const timestamp =
Date.now() are declared (immediately after the function signature that contains
threshold) and delete those two comment lines so the code reflects current
reality.

---

346-348: Performance consideration: querySelectorAll('*') can be expensive.

Querying all elements in the document could be slow on pages with large DOMs. Consider documenting this trade-off or potentially offering a way to scope the audit to specific containers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/custom-audit.utils.ts` around lines 346
- 348, The use of context.querySelectorAll('*') (assigned to allElements) can be
very costly on large DOMs; update the relevant audit function to accept an
optional container/root parameter or selector (e.g., rootElement or
rootSelector) and use rootElement.querySelectorAll('*') instead of querying the
entire context by default, or document the performance trade-off in the function
comment and provide a scoped alternative method (e.g., queryWithin(container) or
an options object) so callers can limit the audit to a subtree when needed.

packages/devtools-a11y/src/core/utils/ally-audit.utils.ts (2)

1-1: Filename typo: "ally" should be "a11y".

The filename ally-audit.utils.ts appears inconsistent with the package naming convention (devtools-a11y). Consider renaming to a11y-audit.utils.ts for consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ally-audit.utils.ts` at line 1, The
file is misnamed "ally-audit.utils.ts" but the package uses "a11y" naming;
rename the file to "a11y-audit.utils.ts" and update all imports/usages that
reference "ally-audit.utils.ts" to the new filename (search for import paths
referencing ally-audit.utils or the module that exports from it), ensuring any
tooling/config (exports index, barrel files, tests) is updated to the new name
so imports like import ... from '.../a11y-audit.utils' resolve correctly.

---

21-29: Duplicate constant: IMPACT_SEVERITY is duplicated as SEVERITY_ORDER in ui.utils.ts.

Both files define identical severity-to-number mappings. This creates a maintenance burden if the values ever need to change.

Consider exporting SEVERITY_ORDER from one location and importing it in the other.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ally-audit.utils.ts` around lines 21 -
29, IMPACT_SEVERITY duplicates SEVERITY_ORDER; remove the duplication by
centralizing the mapping: pick one canonical export (e.g., export const
SEVERITY_ORDER from packages/devtools-a11y/src/core/utils/ally-audit.utils.ts or
vice‑versa), replace the other constant with an import of that exported symbol,
and update any references to use the chosen name (IMPACT_SEVERITY or
SEVERITY_ORDER) so only a single source of truth exists for the
severity-to-number mapping.

packages/devtools-a11y/src/core/utils/ui.utils.ts (3)

478-482: Static analysis: forEach callback return value.

The static analysis tool flags that el.remove() returns undefined from the forEach callback. While functionally correct, using a for...of loop is cleaner and avoids the linter warning.

🔧 Suggested fix

   // Remove tooltips and clear tracking
   const tooltips = document.querySelectorAll(`.${TOOLTIP_CLASS}`)
-  tooltips.forEach((el) => el.remove())
+  for (const el of tooltips) {
+    el.remove()
+  }
   activeTooltips.clear()
   stopScrollListener()
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ui.utils.ts` around lines 478 - 482,
Replace the NodeList.forEach usage that removes tooltip elements with an
explicit for...of loop to avoid returning undefined from the forEach callback:
iterate over the NodeList returned by
document.querySelectorAll(`.${TOOLTIP_CLASS}`) using for (const el of tooltips)
and call el.remove() inside the loop, leaving the subsequent
activeTooltips.clear() and stopScrollListener() calls unchanged; this targets
the tooltip removal block using TOOLTIP_CLASS, activeTooltips, and
stopScrollListener.

---

29-31: Module-level mutable state may cause issues in SSR or multi-instance scenarios.

The activeTooltips Map and scrollHandler are module-level singletons. In SSR environments, accessing document or window will throw. Consider guarding DOM access or documenting that these utilities are client-only.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ui.utils.ts` around lines 29 - 31, The
module exposes module-level mutable singletons activeTooltips and scrollHandler
which cause SSR/multi-instance problems by touching DOM globals; change to
lazy/client-only initialization: remove direct module-level DOM-dependent
initialization and instead create/get these via a function (e.g.,
ensureTooltipState or getTooltipManager) that checks typeof window/document
before accessing DOM, or throw/return no-op in SSR; update usages of
activeTooltips and scrollHandler to call that initializer so multiple instances
or server runs get isolated state and no direct document/window access at module
load time.

---

466-476: Consider consistency: use for...of loop for classList removal.

For consistency with the suggested fix for tooltips and to avoid potential linter warnings, consider using a for...of loop here as well.

🔧 Suggested fix

 export function clearHighlights(): void {
   // Remove highlight classes
   const highlighted = document.querySelectorAll(`.${HIGHLIGHT_CLASS}`)
-  highlighted.forEach((el) => {
+  for (const el of highlighted) {
     el.classList.remove(
       HIGHLIGHT_CLASS,
       `${HIGHLIGHT_CLASS}--critical`,
       `${HIGHLIGHT_CLASS}--serious`,
       `${HIGHLIGHT_CLASS}--moderate`,
       `${HIGHLIGHT_CLASS}--minor`,
     )
-  })
+  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/utils/ui.utils.ts` around lines 466 - 476,
Replace the NodeList.forEach call with a for...of loop to iterate over
highlighted elements and remove classes; locate the highlighted variable
assigned via document.querySelectorAll(`.${HIGHLIGHT_CLASS}`) and change the
callback that calls el.classList.remove(...) to an explicit for (const el of
highlighted) { el.classList.remove(HIGHLIGHT_CLASS,
`${HIGHLIGHT_CLASS}--critical`, `${HIGHLIGHT_CLASS}--serious`,
`${HIGHLIGHT_CLASS}--moderate`, `${HIGHLIGHT_CLASS}--minor`) } to match the
tooltip fix style and avoid linter warnings.

packages/devtools-utils/src/solid/class.ts (1)

57-66: ⚠️ Potential issue | 🔴 Critical

Formatting improvements look good, but the race condition concern remains unaddressed.

The blank line additions improve readability by separating the guard check, abort path, and normal unmount path.

However, the race condition previously flagged on lines 58-61 still exists: clearing #isMounting = false in the abort path (line 60) allows a concurrent mount() to start before the in-flight mount observes #abortMount and exits. The second mount() would reset #abortMount = false (line 34), causing the first mount to proceed anyway—potentially double-mounting.

Note: The main devtools package (packages/devtools/src/core.ts:103-106) uses the identical pattern, so any fix should be applied consistently to both.

,

Suggested fix (per prior review)

       if (this.#isMounting) {
         this.#abortMount = true
-        this.#isMounting = false
         return
       }

The in-flight mount() already sets #isMounting = false when it detects #abortMount (line 40-41), so removing the duplicate clear in unmount() keeps the guard intact until the async operation completes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-utils/src/solid/class.ts` around lines 57 - 66, In
unmount(), when handling the abort path don't clear the in-flight mount guard
(`#isMounting`) — only set `#abortMount` = true and return so the active async
mount() can observe `#abortMount` and set `#isMounting` = false itself; remove the
line that sets this.#isMounting = false from the abort branch in the unmount()
method (references: unmount(), mount(), private fields `#isMounting` and
`#abortMount`, and cleanup via `#dispose/`#isMounted) and apply the identical change
to the same pattern in the main devtools implementation in
packages/devtools/src/core.ts so both locations behave consistently.

packages/devtools-a11y/src/core/core.tsx (1)

5-5: ⚠️ Potential issue | 🟠 Major

Replace empty interface to clear the Biome error.

Line 5 triggers noEmptyInterface; this is currently a lint error and may fail checks.

Proposed fix

-export interface A11yDevtoolsInit {}
+/** Placeholder for future core initialization options. */
+export type A11yDevtoolsInit = Record<string, never>

As per coding guidelines, **/*.{js,ts,jsx,tsx}: JSDoc should read like documentation as it gets converted to markdown docs for the website.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/core.tsx` at line 5, Replace the empty
interface A11yDevtoolsInit with a type alias to satisfy the noEmptyInterface
rule: change the declaration in core.tsx from "export interface A11yDevtoolsInit
{}" to a type alias such as "export type A11yDevtoolsInit = Record<string,
unknown>"; also add a concise JSDoc comment above the type per project
guidelines so it will render correctly in generated docs.

packages/devtools-a11y/src/core/core.tsx (1)

5-5: ⚠️ Potential issue | 🟡 Minor

Resolve the empty public init type (still equivalent to {}).

Line 5 keeps an empty interface, which still trips Biome and leaves the public API ambiguous. This was already flagged earlier and remains unresolved.

Proposed fix

-export interface A11yDevtoolsInit {}
+export type A11yDevtoolsInit = Record<string, never>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/src/core/core.tsx` at line 5, The exported
A11yDevtoolsInit interface is empty and should be made explicit to avoid
ambiguous public API; replace the empty interface declaration (A11yDevtoolsInit)
with a clear type alias such as export type A11yDevtoolsInit = Record<string,
never> (or export type A11yDevtoolsInit = unknown if you intend an opaque init)
and update any usages/imports to the new type alias so linters and consumers see
an intentional, non-empty public contract.

packages/devtools-a11y/package.json (1)

92-112: ⚠️ Potential issue | 🟡 Minor

Mark @types/react as optional in peer metadata.

Line 93 declares @types/react as a peer, but it is missing from peerDependenciesMeta. This can still generate peer warnings for consumers that do not install React types.

🔧 Proposed fix

  "peerDependenciesMeta": {
+   "@types/react": {
+     "optional": true
+   },
    "preact": {
      "optional": true
    },
    "react": {
      "optional": true
    },

In npm package.json, if "@types/react" is listed in peerDependencies but omitted from peerDependenciesMeta.optional, will consumers without "@types/react" receive unmet peer dependency warnings?

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/devtools-a11y/package.json` around lines 92 - 112, Add
"@types/react" to the peerDependenciesMeta.optional section so it is treated as
optional like the other framework peers: update the package.json to include an
entry for "@types/react" under "peerDependenciesMeta" with "optional": true,
ensuring the existing "peerDependencies" list (which currently contains
"@types/react") remains unchanged; this will prevent npm peer warnings for
consumers who don't install the React types.